Конфигурация кластера в YAML (Cartridge)¶

Документ рассматривает параметры YAML-конфигурации кластеров Tarantool Cartridge, необходимые для взаимодействия с TCF. Например, вы можете задать TCF-специфичные настройки кластера, отправив HTTP-запрос с необходимой YAML-конфигурацией на адрес /admin/config.

Для работы кластера Tarantool Cartridge с TCF используется блок конфигурации cluster_federation.

cluster_federation¶

Блок конфигурации cluster_federation содержит следующие параметры:

cluster_1
cluster_2
initial_status
dml_users
replication_user
replication_password
storage
storage_params
gateway
destination
authorization
status_ttl
enable_system_check
failover_timeout
health_check_delay
max_suspect_counts

cluster_1¶

Имя кластера, для которого применяется конфигурация. Имя используется в качестве префикса etcd для хранения информации о состоянии кластера.

Тип: string

Пример:

cluster_federation:
  cluster_1: cluster_a
  cluster_2: cluster_b
  # ...

cluster_2¶

Имя соседнего кластера. Имя используется в качестве префикса etcd для хранения информации о состоянии кластера.

Тип: string

initial_status¶

Состояние, в которое кластер переходит при первом запуске с использованием TCF.

Возможные значения: active, passive

Пример:

cluster_federation:
  initial_status: active
  # ...

dml_users¶

Список пользователей, доступ которым заблокирован на пассивном кластере.

После смены состояния балансировщик может не сразу получить информацию об изменении состояния и какое-то время продолжит направлять трафик на пассивный кластер. dml_users необходима, чтобы заблокировать пользователя, от имени которого приложение отправляет запросы на пассивный кластер.

Тип: array

Пример:

cluster_federation:
  # ...
  dml_users:
    - db_user

replication_user¶

Имя пользователя для подключения репликаторов TCF.

Тип: string

Пример:

cluster_federation:
  # ...
  replication_user: replicator
  replication_password: foobar

replication_password¶

Пароль пользователя replication_user.

Тип: string

storage¶

Внимание

Параметры storage и storage_params в конфигурации кластера Cartridge используются в случае, если второй кластер работает на Tarantool 3.x.

Тип хранилища конфигурации, которое используется для хранения состояния кластеров.

Возможные значения: config_storage, etcd_v3, etcd_v2.

storage_params¶

Внимание

Параметры хранилища конфигурации. Набор параметров зависит от выбранного типа хранилища конфигурации – config_storage, etcd_v3 или etcd_v2.

Для типа config_storage доступны следующие параметры:

endpoints – массив узлов хранилища config_storage с возможностью указания нескольких подключений. Параметр доступен начиная с версии 0.6.0. Тип: array. Возможные параметры:
- uri – адрес master-узла хранилища конфигурации для типа config_storage, указанный внутри каждого объекта в массиве endpoints. Тип: string;
- login – имя пользователя для доступа к хранилищу конфигурации. Тип: string;
- password – пароль для доступа к хранилищу конфигурации. Тип: string;
- params – дополнительные параметры подключения к хранилищу. Возможные параметры:
  - ssl_key_file – путь к закрытому ключу. Тип: string;
  - ssl_cert_file – путь к сертификату. Тип: string;
  - ssl_ca_file – путь к корневому сертификату. Тип: string;
  - ssl_ciphers – список наборов шифров TLS, разделенных двоеточиями. Тип: string;
  - ssl_password – пароль для зашифрованного закрытого ключа SSL. Тип: string;
  - ssl_password_file – текстовый файл, содержащий пароли для зашифрованных ключей SSL. Тип: string;
uri – адрес master-узла хранилища конфигурации для типа config_storage. Параметр удален начиная с версии 0.6.0. Тип: string, key-value;
login – имя пользователя для доступа к хранилищу конфигурации. Параметр удален начиная с версии 0.6.0. Тип: string;
password – пароль для доступа к хранилищу конфигурации. Параметр удален начиная с версии 0.6.0. Тип: string;
timeout – время ожидания выполнения запроса в секундах. Тип: number. Значение по умолчанию: 1. В версии 0.7.0 параметр переименован из request_timeout в timeout;
prefix – префикс, под которым хранится конфигурация. Параметр доступен начиная с версии 0.4.0. Тип: string;
params – дополнительные параметры подключения к хранилищу. Набор параметров совпадает со списком опций функции Tarantool net_box.connect(). Параметр удален начиная с версии 0.6.0;
uri.params - настройки SSL. Параметр удален начиная с версии 0.6.0. Возможные параметры:
- ssl_key_file – путь к закрытому ключу. Тип: string;
- ssl_cert_file – путь к сертификату. Тип: string;
- ssl_ca_file – путь к корневому сертификату. Тип: string;
- ssl_ciphers – список наборов шифров TLS, разделенных двоеточиями. Тип: string;
- ssl_password – пароль для зашифрованного закрытого ключа SSL. Тип: string;
- ssl_password_file – текстовый файл, содержащий пароли для зашифрованных ключей SSL. Тип: string.

Для типа etcd_v3 доступны следующие параметры:

endpoints – URI экземпляров хранилища конфигурации. Тип: array;
login – имя пользователя для доступа к хранилищу конфигурации. Тип: string;
password – пароль для доступа к хранилищу конфигурации. Тип: string;
prefix – префикс, под которым хранится конфигурация. Значение по умолчанию: /tcf. Параметр доступен начиная с версии 0.4.0. Тип: string;
lock_delay – время в секундах, в течение которого блокировка остается активной после разрыва соединения. После этого она автоматически снимается. Тип: number;
request_timeout – время в секундах, в течение которого должен выполниться запрос к etcd. Если за это время ответа нет, запрос считается неудачным. Тип: number;
http.request.timeout – время ожидания выполнения запроса в секундах. Тип: number. Значение по умолчанию: 1;
http.request.unix_socket – Unix-сокет для подключения к хранилищу конфигурации. Тип: string;
ssl.ca_file – путь к корневому сертификату. Тип: string;
ssl.ca_path – путь к директории, содержащей сертификаты. Тип: string;
ssl.ssl_cert – путь к сертификату. Тип: string;
ssl.ssl_key – путь к закрытому ключу. Тип: string;
ssl.verify_host – верифицировать имя сертификата (CN) с указанным хостом. Тип: boolean;
ssl.verify_peer – верифицировать SSL-сертификаты. Тип: boolean;
watchers.reconnect_max_attempts – максимальное число попыток подключения к хранилищу в случае ошибок подключения. Тип: integer;
watchers.reconnect_timeout – время ожидания в секундах между попытками подключения к хранилищу в случае ошибок подключения. Тип: number.

Для типа etcd_v2 доступны следующие параметры:

endpoints – URI экземпляров хранилища конфигурации. Тип: array;
username – имя пользователя для доступа к хранилищу конфигурации. Тип: string;
password – пароль для доступа к хранилищу конфигурации. Тип: string;
prefix – префикс, под которым хранится конфигурация. Значение по умолчанию: /tcf. Параметр доступен начиная с версии 0.4.0. Тип: string;
lock_delay – длительность блокировки в секундах. Тип: number. Значение по умолчанию: 10.

gateway¶

Параметры экземпляра Gateway.

Тип: map

Если эта опция задана, TCF-worker будет управлять состоянием Gateway: автоматически отключать Gateway на пути из пассивного кластера в активный и включать Gateway на пути из активного кластера в пассивный с помощью HTTP-адресов обработчиков запросов /api/v1/start и /api/v1/stop. При этом репликация будет односторонней. Если секция cluster_federation.gateway отсутствует, репликация будет двусторонней.

Поддерживаемые параметры:

uri – URI для подключения к экземпляру Gateway. Тип: string;
http_server – параметры для установки соединения к серверу. Тип: map. Поддерживаемые параметры:
- ssl_ca_file– путь к файлу корневого сертификата, который используется для проверки подлинности клиента при установке TLS-соединения. Тип: string;
- ssl_cert_file – путь к файлу сертификата сервера. Тип: string;
- ssl_key_file– путь к файлу закрытого ключа сервера. Тип: string.

Пример:

cluster_federation:
  gateway:
    uri: "http://localhost:8080"
    http_server:
      ssl_cert_file: "/etc/certs/gateway.crt"
      ssl_key_file: "/etc/certs/gateway.key"
      ssl_ca_file: "/etc/certs/gateway.ca"
  # ...

destination¶

Параметры экземпляра Destination.

Тип: map

Опция cluster_federation.destination делает возможным плавное переключение без потери данных (graceful toggle), если при отправке запроса на HTTP-адрес обработчика /api/v1/status приходит ответ с HTTP-кодом 200 и в теле ответа содержится статус connected (соединение установлено) или streaming (репликация активна).

Поддерживаемые параметры:

uri – URI для подключения к экземпляру Gateway. Тип: string;
http_server – параметры для установки соединения к серверу. Тип: map. Поддерживаемые параметры:
- ssl_ca_file– путь к файлу корневого сертификата, который используется для проверки подлинности клиента при установке TLS-соединения. Тип: string;
- ssl_cert_file – путь к файлу сертификата сервера. Тип: string;
- ssl_key_file– путь к файлу закрытого ключа сервера. Тип: string.

Пример:

cluster_federation:
  destination:
    uri: "http://localhost:8080"
    http_server:
      ssl_cert_file: "/etc/certs/destination.crt"
      ssl_key_file: "/etc/certs/destination.key"
      ssl_ca_file: "/etc/certs/destination.ca"
  # ...

authorization¶

Доступно с версии 0.9.0.

Параметры авторизации для HTTP API кластера Tarantool Cartridge.

Поддерживаемые параметры:

provider – имя провайдера. На текущий момент поддерживается только значение keycloak. Тип: string;
provider_params – параметры провайдера Keycloak. Тип: map. Поддерживаемые параметры:
- url – URL сервера Keycloak. Тип: string;
- ssl – параметры TLS для HTTP API Keycloak. Тип: map. Поддерживаемые параметры:
  - ca_file– путь к файлу корневого сертификата, который используется для проверки подлинности клиента при установке TLS-соединения. Тип: string;
  - cert_file – путь к файлу сертификата сервера. Тип: string;
  - key_file– путь к файлу закрытого ключа сервера. Тип: string;
- roles – список с соответствием ролей из Keycloak и правил авторизации для кластера Tarantool Cartridge. Тип: map. Поддерживаемые параметры:
  - info – чтение статусов кластеров и метрик. Дает доступ к HTTP-адресам обработчиков запросов: /tcf/status, /tcf/is_active, /tcf/clusters (TCF-worker) и /api/v1/status (Destination). Значение по умолчанию: TCF_INFO. Тип: string;
  - toggle – управление репликацией. Дает доступ ко всем адресам обработчиков запросов, кроме /api/v1/rebootstrap (Destination). Значение по умолчанию: TCF_TOGGLE. Тип: string;
  - admin – полный доступ ко всем адресам обработчиков запросов, включая /api/v1/rebootstrap. Значение по умолчанию: TCF_ADMIN. Тип: string;
- client_id – имя сервисного клиента. Тип: string;
- client_secret_path – путь до файла с секретом клиента. Тип: string. Для безопасности необходимо создать текстовый файл с секретом внутри;
- realm – имя области realm, в которой создан сервисный клиент. Тип: string.

Компоненты Gateway и Destination предоставляют HTTP API, к которому технологическая роль TCF-worker делает запросы внутри кластера Tarantool Cartridge. Для таких внутренних запросов используются параметры client_id, client_secret_path и realm. Чтобы эти запросы работали корректно, необходимо:

Заполнить поля cluster_federation.gateway или cluster_federation.destination в конфигурации TCF-worker.
Создать конфиденциального клиента с включенным сервис-аккаунтом serviceAccountsEnabled=true. Клиент должен иметь роль toggle или admin. Через этого клиента будут выписываться токены для обращения TCF-worker к компонентам Gateway/Destination.
Добавить параметры authorization.provider_params.client_id, authorization.provider_params.client_secret_path и authorization.provider_params.realm в конфигурацию.

Пример:

cluster_federation:
  authorization:
    provider: keycloak
    provider_params:
      url: "https://keycloak.example.com/"
      roles:
        info: ORDERDB_TCF_INFO
        toggle: ORDERDB_TCF_TOGGLE
        admin: ORDERDB_TCF_ADMIN
      client_id: "client"
      client_secret_path: "/path/to/file"
      realm: "myrealm"
      ssl:
        ca_file: "/etc/ssl/certs/keycloak-ca.pem"
        cert_file: "/etc/ssl/certs/client.pem"
        key_file: "/etc/ssl/private/client-key.pem"

status_ttl¶

Время (в секундах), через которое может произойти автоматическое переключение состояния кластеров.

Тип: number

Значение по умолчанию: 4

enable_system_check¶

Включить сервис проверки доступности файловой системы.

Тип: boolean

Значение по умолчанию: true

failover_timeout¶

Время (в секундах) захвата флага активным координатором. Если активный координатор вышел из строя и в активном кластере не осталось доступных координаторов, будет произведено переключение статусов кластеров.

Тип: number

Значение по умолчанию: 20

health_check_delay¶

Периодичность (в секундах) опроса проверки состояния кластера координатором. Каждая последующая неудачная проверка увеличивает счетчик suspect_counts на 1. См. также max_suspect_count.

Тип: number

Значение по умолчанию: 3

max_suspect_counts¶

Максимальное значение счетчика suspects_counts, после которого координатор складывает полномочия и производится переключение состояния кластеров. См. также health_check_delay.

Тип: number

Значение по умолчанию: 3

Версия:

Конфигурация кластера в YAML (Cartridge)¶

cluster_federation¶

cluster_1¶

cluster_2¶

initial_status¶

dml_users¶

replication_user¶

replication_password¶

storage¶

storage_params¶

gateway¶

destination¶

authorization¶

status_ttl¶

enable_system_check¶

failover_timeout¶

health_check_delay¶

max_suspect_counts¶